LotusScript Doc

LotusScript library: LSALibBasic

Options
Public
Declare

Uses
LSALibMessageHandler

Global variables
Private ThisMsg = LSAMessage
Private PatternS List = Pattern
Private PatternSUb = Integer
Private InstanceS List = Variant
Public InstanceSUbound = Integer
Public ContextDoc = NotesDocument
Public InstanceName = String

Types
Public Pattern

The motivation for this module is, to be able to use instances defined in a subfrom within a form Context or vice versa. This is usually impossible because the scope of the global variables is restricted to either a form or a subform.
The instance manager is a central place to register instances of a class and to retrieve them from any place. You may
For example:
Assume you have the following code in the form
Dim MyHandle as String
Dim MyInstance as MyClass
Set MyInstance = New MyClass(...)
MyHandle = ICheckInHandle(MyInstance , "MyUniqueSuggestedID")
MyInstance.AttribX
:
in the subform you can refere to it
Dim MyLocalInstance as New MyClass
Set MyLocalInstance = Irefer( "MyUniqueSuggestedID", Nothing)
' continue your code as if the instance would be owned by the subform form.
MyLocalInstance.AttribX
:
Usually the destructor of a class 'delete' will call
ICheckout Me

As OCIMgr is designed to work together with classes generated by the "OCards", a tool for specification of objects and code generation, the "IcheckInOC" assumes the instance to carry the current Notes Document in the class variable "ContextDoc" as well as the suggested ID in "ContextInstanceId".
If your class is does not follow this conventions, you have to use the "IcheckInOCHandle" method.
An Internal handle allways makes sure that there is a unique key by adding a time stamp with accuracy of a second and within that a random number of 3 digits to the suggested ID.
OCIMgr is a base functionality that needs no prerequisites nor configuration.

Author:
LPS EMEA
Version:
2.0.0 24.MAR.2000
History:
24.MAR.2000EScextracted functionality from the former Imgr
24.MAR.2000EScadded a general Functionality ICheckInOC and IcheckInHandle for Ocard instances and arbitrary objects.
02.MAY.2000EScAdded robust handling for IRefer in case of invalid references to instances
08.JUN.2000EScAllow handle as parameter to ICheckOut and randomize handle below subsecond level
12.SEP.2000GGHandling of Rnd() fixed to avoid same random number during one second


Method Summary
Function CNames (InputNames As Variant, NameType As String) As String
Function CodeDateTime (ProcessDate As Variant) As String
Function Empty () As Variant
Function GetNameTypes () As Variant
Sub ICheckIn (Instance As Variant)
Function ICheckInHandle (instance As Variant, suggestedID As String) As String
Sub ICheckInOC (Instance As Variant)
Sub ICheckOut (Instance As Variant)
Sub Initialize ()
Function IRefer (Handle As String, Context As Variant) As Variant
Sub IRename (Instance As Variant, InstanceId As String)
Function parseCGI (what As String, doc As Variant) As String
Function SetDocHistory (doc As NotesDocument) As Integer
Function Vappend (array As Variant, AppendArray As Variant) As Variant
Function VContains (sourceValues As Variant, containValues As Variant) As Integer
Function Vdate (argument As Variant) As Variant
Function VDelimiters (delChars As String) As Variant
Function VEqual (arr1 As Variant, arr2 As Variant) As Integer
Function VExpand (Mastertext As String, Replacements As Variant) As String
Function VExpandOpt (Mastertext As String, Replacements As Variant, opt As String) As String
Function VExpandPlaceholder (arg As String, Replacements As Variant, Terminates As String, opt As Integer) As Variant
Function VExpandText (Arg As String, Replacements As Variant, Skip As Integer, Cond As Integer, Opt As Integer) As String
Function VExplode (Arg As Variant, Delimiter As Variant) As Variant
Function VFormulaStr (Array As Variant) As Variant
Function VImplode (Arg As Variant, Delimiter As Variant) As String
Function VLeft (Array As Variant, Delim As Variant) As Variant
Function VLeftBack (Array As Variant, Delim As Variant) As Variant
Function VMatches (Array As Variant, Pattern As String) As Integer
Function VMatchesPattern (CheckStr As String, Byval PatternSIx As Integer) As Integer
Function VNames (InputNames As Variant) As String
Function VReplaceSubstring (inArray As Variant, FromArray As Variant, ToArray As Variant) As Variant
Function VRight (Array As Variant, Delim As Variant) As Variant
Function VRightback (Array As Variant, Delim As Variant) As Variant
Function VScriptStr (Array As Variant) As Variant
Function VSort (Arg As Variant) As Variant
Function Vtrim (array As Variant) As Variant
Function VTwinSort (Argument As Variant, TwinArgument As Variant) As Variant
Function VUnique (array As Variant) As Variant

Method Detail

VExplode

Public Function VExplode(Arg As Variant,Delimiter As Variant) As Variant
Splits the Args into items with regard to the delimiters. Datatypes are preserved. Single values are always returned as an one element array.
Example
"abc,def;ghi":"jkl;mno" and ",":";" as delimiters would result in the five element array "abc":"def":"ghi":"jkl":"mno"

Parameters:
ArgVariantarray or single value of type string, number, date or EMPTY
DelimiterVariantarray of strings used toseparate the items.
Returns:
Variantthe resulting array of splitted items
See also:
LSALibFct#Vimplode
LSALibFct#VDelimiters
History:
02.SEP.1996ESc
Summmary Top

VImplode

Public Function VImplode(Arg As Variant,Delimiter As Variant) As String
Glues the items in Arg into a string, in which the items are separated by delimiters. If delimiter is an array it will use the first element of the delimiters.
Example
"abc":"def":"ghi":"jkl":"mno" and";" as delimiters would result in the string "abc;def;ghi;jkl;mno"

Parameters:
ArgVariantarray or single value of type string, number, date or EMPTY
DelimiterVariantcontaining a string used to separate the items.
Returns:
Variantthe resulting array of joined, delimited items
See also:
LSALibFct#VExplode
History:
08.NOV.1996ESc
Summmary Top

VDelimiters

Public Function VDelimiters(delChars As String) As Variant
Creates an array of delimiters from the characters in delChars. If the character is If both FF and LF are used, specify FF first in order to proces the empty lines first.

Parameters:
delCharsStringused to create the array of separator.
Returns:
Variantthe resulting array of splitted items
See also:
LSALibFct#VExplode
History:
02.Sep.1996ESc
Summmary Top

VSort

Public Function VSort(Arg As Variant) As Variant
Sorts the items in the Arg. These items may be of any type that can be compared.
The algorithm curently is a simple bubble sort and is stabile and fastest on sorted arrays

Parameters:
ArgVariantthe array of items to be sorted or EMPTY
Returns:
Variantthe sorted array.
History:
25.APR.1997ESc
Summmary Top

VTwinSort

Public Function VTwinSort(Argument As Variant,TwinArgument As Variant) As Variant
Sorts the items in the TwinArgument based upon the corresponding values in the Argument.The items in Argument may be of any type that can be compared. Both Arrays need to have the same number of elements except when the TwinArgument is EMPTY. Given the TwinArgument is EMPTY we return the sorted indices.
The algorithm currently is a simple bubble sort is stabile and fastest on sorted Arrrays

Parameters:
ArgumentVariantthe Arrray of sortkeys Or EMPTY
TwinArgumentVariantthe Arrray of items to be sorted
Returns:
Variantthe sorted output.
Errors:
ErrArgDimMismatchif Arguments have unequal dimensions
History:
13.JAN.1998ESc
Summmary Top

VExpandPlaceholder

Private Function VExpandPlaceholder(arg As String,Replacements As Variant,Terminates As String,opt As Integer) As Variant
Summmary Top

VExpandText

Private Function VExpandText(Arg As String,Replacements As Variant,Skip As Integer,Cond As Integer,Opt As Integer) As String
Summmary Top

VExpandOpt

Public Function VExpandOpt(Mastertext As String,Replacements As Variant,opt As String) As String
This routine is a Generalization of the VExpand, which allows to specify the behaviour in case of invalid placeholders. Interprets the mastertext and replaces the Placeholders with th ereplacements provided. The mastertext specification follows an easy syntax notation including conditions that are handeled recursively.The syntax is formally described in the VExpand command.
The function is based on the auxilary routine VExpandText.

Parameters:
MastertextStringthe definition of the format
ReplacementsVariantmay be an array of values, a list of values, a notesDocument instance, or even an instance of an OCard generated class, that provides GetAttribByName.
Optstringspecification of the behaviour in case of missing replacements See above
Returns:
Stringthe expanded mastertext.
Errors:
ErrIncompleteConditionif the mastertext can't be interpreted more errors see VExpandText
See also:
LSALibFct#VExpand
History:
21.JUN.1998ESc
Summmary Top

VExpand

Public Function VExpand(Mastertext As String,Replacements As Variant) As String
Interprets the mastertext and replaces the Placeholders with the replacements provided. The mastertext specification follows an easy syntax notation including conditions that are handeled recursively. It uses the default error handling in case of undefined placeholders.
This makes it easy to specify the different formats e.g an addresslabel, of a phone number or alike.
The syntax is formally described below using the following notational convention
{mastertext}={expression} [ {mastertext} ]
{expression}= {text} | "<"{placeholder} [ ";" {format} ]">" | "<"{basicplace}">" | "["{condition}"]"
{text}= "" or any character except ";" or "[" or "]" or {op}
{op}= ">" | "<" | "=" | "><" | "<>"
{placeholder}= {ix} | {Id} | {attrib}
{basicplace}= "[" | "]" | "SC" | "LF" | "EQ" | "GR" | "LE" | "NE" | "HT" | "NL"
GR we return >
LE we return <
EQ we return =
NE we return <>
SC we return ;
HT we return Horizontal tabulator (Char 9 )
LF we return Line feed (Char 10 ) for use in Dialogs!
NL we return Line feed (Char 0 )
[ or ] we return the corresponding character
{ix} is a number, we return the corresponding array-element of the Replacements,
{Id} is a String, we return the corresponding list-element of the Replacements. If the name is EMPTY we return "". Leading and trailing spaces are ignored.
{attrib} an Instance of a business object we return the coresponding field value.If the name is EMPTY we return "". Leading and trailing spaces are ignored. If there is no replacement specification is given, we return the attribname itself.
{Format} = {integer} | {fmt}
{fmt} any Lotus script format like > for uppercase, Percent see Lotus Script function Format[$] ( expr [ , fmt ] )
{integer} any positive or negative number which chunks the number into character portions as given by the integer e.g 1234567890 and format 3 results in 123 456 789 0 while -4 results in 12 3456 7890
{condition} = {operand} [ {Op} {operand} ] ";" {truecase} [";" {falsecase} ]
if the second operand is omitted, we test that the first operand in not EMPTY
{truecase} = {mastertext}
{falsecase}= {mastertext}
{operand} = {placeholder} | text

Example:
Given <PCountry> is 49, <PArea> is 211, <PLine> is 51896, <PExtension> is 99, and the mastertext is
[<PCountry>;+<PCountry> -][<PArea>; (0) <PArea;3> - ]<PLine;3>[<PExtension>; - <PExtension;3>]
the expanded phonenumber would be
+49 (0) 211 - 518 96 - 99

Parameters:
MastertextStringthe definition of the format
ReplacementsVariantmay be an array of values, a list of values, a notesDocument instance, or even an instance of an OCard generated class, that provides GetAttribByName.
Returns:
Stringthe expanded mastertext.
Errors:
ErrIncompleteConditionThe mastertext can't be fully interpreted, usually a nesting issue
ErrCharAfterCondA condition is not terminated correctly
ErrCharInPlaceholderA placeholder is not terminated correctly
ErrListItemDoesNotExistA placeholder dies not exist
ErrCharAfterOperator1The operator is invalid
ErrCharAfterOperator2The operator is invalid
ErrCharInTrueA true case is not terminated correctly
ErrCharInFalseA false case is not terminated correctly
See also:
LSALibFct#VExpandOpt
History:
21.JUN.1998ESc
Summmary Top

Vappend

Public Function Vappend(array As Variant,AppendArray As Variant) As Variant
Appends the items of the array and the AppendArray into an combined array. If one of the arguments is EMPTY it is ignored, that does not mean that empy elements are ignored. The Items can be any type such as string, integer or others. If the parameter is an individual element , e.g a string, it is treated as an array with one element only.

Parameters:
ArrayVariantmay be EMPTY, an item or an array of items of any type
AppendArrayVariantmay be EMPTY, an item or an array of items of any type
Returns:
Variantthe items concatenated into an array or EMPTY
History:
06.APR.1998ESc
Summmary Top

VUnique

Public Function VUnique(array As Variant) As Variant
Deletes all duplicates from the input array. The input may be EMPTY, an item or an array of items of any type as long as the can be compared.

Parameters:
ArrayVariantEMPTY, an item or an array of items of any type
Returns:
VariantEMPTY or the resulting array of unique elements
History:
22.FEB.1997ESc
Summmary Top

Vtrim

Public Function Vtrim(array As Variant) As Variant
Trims all items and deletes all EMPTY items from the input array. The input may be EMPTY, an item or an array of items of type string.

Parameters:
ArrayVariantEMPTY, an item or an array of items of type string
Returns:
VariantEMPTY or the resulting array of trimmed elements
History:
25.APR.1997ESc
Summmary Top

Vdate

Public Function Vdate(argument As Variant) As Variant
Validates any argument that can be a date and returns a valid Lotus Script datetime. Argument can be any of the following Vdate combines the conversion of both NotesDateTime and Script DatTime into one flexible routine

Parameters:
argumentVariantanything that can be interpreted as a date/time
Returns:
Varianta valid Lotus Script DateTime
Errors:
TypeMissmatchThe input argument can't be interpreted as a valid date
History:
08.NOV.1996ESc
Summmary Top

Empty

Public Function Empty As Variant
Creates the value EMPTY, which is missing from the constants in Lotus Script.

Returns:
Variantwith the value EMPTY
History:
25.APR.1997ESc
Summmary Top

GetNameTypes

Public Function GetNameTypes As Variant
Provides you with an array with the valid name types as expected by CNAMES. Usually the first element"ABBREVIATE" is used as a default value. The list includes both the NameTypes as used by the @Names function as well as the Lotus Script class NotesName.

Returns:
Variantarray with the various Name formats
See also:
LSALibFcr#CNames
History:
30.SEP.1996ESc...
Summmary Top

VNames

Public Function VNames(InputNames As Variant) As String
Validates a name and convertsit via the NotesName Object in Lotus Script into a canonicalized string.

Parameters:
InputVariant
Returns:
Varianta string in a canonicalized form
Errors:
ErrVNamesNothingEnteredNothing entered
ErrTypeMismatchif the string is not CANONICALIZABLE (contains no backslashes), an Error is generated
History:
20.FEB.1997ESc
Summmary Top

CNames

Public Function CNames(InputNames As Variant,NameType As String) As String
Converts a proper name in inputNames into a string according to the NameType given as a second parameter. NameTypes are those provided by CNames but also those used by the @Names function, which differs from the property names of the NotesName object.
HINT:
There are NameTypes, that do not return results as expected like Surname, PRMD, ... Example
InputName "Martin Musteman/MyComp/DE" and NameType be "abbreviated" results in
"Martin Musterman/MyComp/DE"

Parameters:
InputNamesVariantthe
InputTypeStringthe format code like "CN", "Abbreviate" etc.
Returns:
Stringa new object of class x
See also:
LSALibFct#GetNameTypes
History:
03.APR.1997EScInserted header
Summmary Top

VLeft

Public Function VLeft(Array As Variant,Delim As Variant) As Variant
Returns for each item in an array of strings the portion left of the first occurence of delimiter from left to right. The function is similar to @Left. If the delimiter is not contained in the array , the result is an empty string. Should the delimiter be an array, the first element is worked with.

Parameters:
ArrayVariantthe items to be processed
DelimVariantthe delimiter to be searched for
Returns:
Variantarray of the left portions of the items in Array
History:
22.DEC.1998ESc
Summmary Top

VRight

Public Function VRight(Array As Variant,Delim As Variant) As Variant
Returns for each item in an array of strings the portion right of the first occurence ofdelimiter from left to right. The function is similar to @Right. If the delimiter is not contained in the array, the result is an empty string. Should the delimiter be an array, the first element is worked with.

Parameters:
ArrayVariantthe items to be processed
DelimVariantthe delimiter to be searched for
Returns:
Variantarray of the right portions of the items in Array
History:
02.OCT.1998ESc
Summmary Top

VLeftBack

Public Function VLeftBack(Array As Variant,Delim As Variant) As Variant
Returns for each item in an array of strings the portion left of the last occurence of delimiter from left to right. The function is similar to @LeftBack. If the delimiter is not contained in the array, the result is an EMPTY string. Should the delimiter be an array, the first element is worked with.

Parameters:
ArrayVariantthe items to be processed
DelimVariantthe delimiter to be searched for
Returns:
Variantarray of the left portions of the items in Array
History:
02.OCT.1998ESc
Summmary Top

VRightback

Public Function VRightback(Array As Variant,Delim As Variant) As Variant
Returns for each item in an array of strings the portion right of the last occurence of delimiter from left to right. The function is similar to @RightBack. If the delimiter is not contained in the array, the result is an EMPTY string. Should the delimiter be an array, the first element is worked with.

Parameters:
ArrayVariantthe items to be processed
DelimVariantthe delimiter to be searched for
Returns:
Variantarray of the right portions of the items in Array
History:
02.OCT.1998ESc
Summmary Top

VFormulaStr

Public Function VFormulaStr(Array As Variant) As Variant
Escapes a string or each item of an Array with the sequences needed for @formulas

Parameters:
ArrayVariantthe items to be processed
Returns:
Variantarray of the masked items in Array
History:
08.JAN.1998ESc
Summmary Top

VScriptStr

Public Function VScriptStr(Array As Variant) As Variant
Escapes a string or each item of an Array with the sequences needed for Strings in Lotus Script

Parameters:
ArrayVariantthe items to be processed
Returns:
Variantarray of the masked items in Array
History:
09.JUN.1998ESc
Summmary Top

parseCGI

Public Function parseCGI(what As String,doc As Variant) As String
This function takes a key and doc as parameters, and return the value that represented by that key. The doc is the sessions document context, which is an in Memory document containing th einformation as provided with the call of the agent.
Example
Let query_string be key=val & Anotherkey= another%20val & . . .) . Ask for "key" the result will be "val" while asking for "Anotherkey" will result in "another val".

Parameters:
WhatStringdenoting the value to retrieve
DocVariantwhich is a NotesDocument Context
Returns:
Stringvalue as asked for.
History:
03.APR.2000EScInserted header
02.MAY.2000EScCompare the Value Name case and pitch insensitively! Handles %20 as blank as well as all hexadecimals preceded by %
Summmary Top

VMatchesPattern

Private Function VMatchesPattern(CheckStr As String,Byval PatternSIx As Integer) As Integer
Summmary Top

VReplaceSubstring

Public Function VReplaceSubstring(inArray As Variant,FromArray As Variant,ToArray As Variant) As Variant
Replaces for each item in an array of strings all items in the fromArray by the corresponding items of the ToArrray.The function is similar to @ReplaceSubstring. If The ToArray has less items than the FromArray, the missing Items are folled up by the last item of the ToArray. VReplaceSubstring will replace all occurences of an replaceItem before it continues with the next one.
The function is based on a simle ReplaceSubstring, that works on a sthing only.
Example:
Let InArray be "ABCDEFABC" and FromArray "ABC":"D":"F" and ToArray "T":"":"S" results in "TEST"

Parameters:
ArrayVariantthe items to be processed
FromArrayVariantthe items to be replaced by the corresponding items
ToArrayVariantthe items to replace the corresponding replaced items
Returns:
Variantarray with all items in Array with the replaced prtions.
Errors:
TypeMismatchis issued if the from Array is EMPTY or has EMPTY values
See also:
LSALibMsgHUtil#ReplaceSubstring
History:
06.FEB.2000ESc
Summmary Top

VMatches

Public Function VMatches(Array As Variant,Pattern As String) As Integer
Checks if in a string or array all items match the the pattern. Similar to @matches but no boolean operators and [ ] instead of {} the following notation is used
Example:
The pattern "T+[aeos]t" would match on "Test", "Toast" but not on "Testing", "test", "West".
the pattern "+[x[]+[]]" would match on "[x]" ,"[[[x]]]
This is the main routine that deals with the variants and creates the global patern list returns true or false

Parameters:
ArrayVariantthe string or array of strings to be checked
PatternStringthe pattern to be checked against
Returns:
Varianta new object of class x
See also:
LSALibFct#VMatchesPattern
History:
03.APR.2000ESccorrected behaviour with +[]] as a pattern ...
Summmary Top

VContains

Public Function VContains(sourceValues As Variant,containValues As Variant) As Integer
Acts like the @Contains function in formula language. Checks if a special string (or a set of strings) is contained in a "source" string. In the case that an array of strings is passed as sourceValue the function checks each of the items. It will return true, as soon as any item contains the one of the compare values.

Parameters:
sourceValuesStringor array or strings which should be checked if they include a special string/characters
containValuesStringor array of strings which are propably included in the sourceValues
Returns:
Booleantrue, if one of the containValues is included in one of the sourceValues
History:
03.APR.2000ESc
Summmary Top

VEqual

Public Function VEqual(arr1 As Variant,arr2 As Variant) As Integer
Compares to string arrays.

Parameters:
arr1Variantfirst array of strings
arr2Variantsecond array of strings
Returns:
Booleantrue, if entries with the same index are equal
History:
02.MAY.2000EScFunctionality included into FCT
Summmary Top

Initialize

Public Sub Initialize
Summmary Top

ICheckInOC

Public Sub ICheckInOC(Instance As Variant)
Checks in an instance into the instance manager with the suggested ID automaticly created This functionality is specific for instances of classes generated by Ocard, in that we make use of the fact that it carries the member variables "Context Doc" and the "Context InstanceId" in the instance .

Parameters:
InstanceVariantany ocard generated instance
Summmary Top

ICheckOut

Public Sub ICheckOut(Instance As Variant)
Remove the Instance from the List as maitained by the instance manager ICheckOut must be caled called in the destructor of a class.

HINT:
If you ommit the checkout, you risk kind of memory leeks, as the instances are preserved until the program comes too a final end. Even system hang ups ( loops ) have been reported
Example:
call ICheckOut(Me)

Dim Handle as String
handle = IcheckInHandle( Myinstance, Myid)
:
call ICheckOut(Me)


Parameters:
InstanceVariantany instance or handle to the instance
Summmary Top

IRename

Public Sub IRename(Instance As Variant,InstanceId As String)

History:
24.MAR.2000EScFunction removed as it is nolonger used
Summmary Top

IRefer

Public Function IRefer(Handle As String,Context As Variant) As Variant
Retrieves the object that is checked in corresponding to the handle. You may call with an incomplete handle if you give a context in which the object lives and which has a creation date as a further qualifier. This context can be a NotesDocument, NotesUIDocument or any class generated by Object cards which document it belongs to. If the instance is not found irefer returns "nothing".

Parameters:
InstanceIDStringthe ID of the instance to be retrieved
ContextVariantthat allows to find a NotesDocument context
Returns:
Variantobject of class x as stored before
History:
02.MAY.2000EScAdded error handling in case of invalid references to instances, they yust passed into the seach loop but instanceId is only available for OC classes.
Summmary Top

ICheckInHandle

Public Function ICheckInHandle(instance As Variant,suggestedID As String) As String
Checks in the instance into the instance manager. A handle is returned which is the prefered way to access the Instance via IRefer or ICheckout. with the suggested ID. If no ID is suggested ("") a random ID is generated.
Example:
MyHandle = ICheckInHandle(Me,"AddrMgr") returns "ADDRMGR#24-12-1999 14:30:59.969" where 969 is a random number

Parameters:
instanceVariantObject of any class
suggestedIDStringsuggestion for the ID
Returns:
StringID by which object can be accessed
See also:
LSALibOCImgr#IRefer
LSALibOCImgr#ICheckOut
Summmary Top

CodeDateTime

Private Function CodeDateTime(ProcessDate As Variant) As String
converts a date into an UDF compliant textual representation like
24-03-2000 15:32:20
If the format is invalid, it returns
00-00-0000 00:00:00

This function is the same as VCodeDateTime but kept here to make this module independent.

Parameters:
ProcessDateVariantof type date
Returns:
Stringthe converted textual date/ time representation
See also:
LSALibFct#VCodeDateTime
Summmary Top

ICheckIn

Public Sub ICheckIn(Instance As Variant)
Old function kept for upward compatibility

See also:
LSALibOCImgr.#ICheckInOC
Summmary Top

SetDocHistory

Public Function SetDocHistory(doc As NotesDocument) As Integer
Summmary Top

TopLotusScript Doc
© Lotus Professional Services
generated on : 05-Apr-01 8:40:00 AM